
<!DOCTYPE html>

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta charset="utf-8" />
    <title>Overview of Single Bubble Model Module &#8212; Texas A&amp;M Oil spill / Outfall Calculator 2.1.0 documentation</title>
    <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
    <script src="../_static/jquery.js"></script>
    <script src="../_static/underscore.js"></script>
    <script src="../_static/doctools.js"></script>
    <script src="../_static/language_data.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="single_bubble_model.Model" href="../autodoc/sbm/single_bubble_model.Model.html" />
    <link rel="prev" title="params.Scales.u_inf_crit" href="../autodoc/params/params.Scales.u_inf_crit.html" />
   
  <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
  
  
  <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />

  </head><body>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          

          <div class="body" role="main">
            
  <div class="section" id="overview-of-single-bubble-model-module">
<h1>Overview of Single Bubble Model Module<a class="headerlink" href="#overview-of-single-bubble-model-module" title="Permalink to this headline">¶</a></h1>
<dl class="field-list simple">
<dt class="field-odd">Release</dt>
<dd class="field-odd"><p>2.1</p>
</dd>
<dt class="field-even">Date</dt>
<dd class="field-even"><p>Jun 05, 2020</p>
</dd>
</dl>
<span class="target" id="module-single_bubble_model"></span><div class="section" id="single-bubble-model">
<h2>Single Bubble Model<a class="headerlink" href="#single-bubble-model" title="Permalink to this headline">¶</a></h2>
<p>Simulate the trajectory of a particle rising through the water column</p>
<p>This module defines the classes, methods, and functions necessary to simulate
the rise of a single particle (bubble, droplet or solid particle) through the
water column. The ambient water properties are provided through the
<cite>ambient.Profile</cite> class object, which contains a netCDF4-classic dataset of
CTD data and the needed interpolation methods. The <cite>dbm</cite> class objects
<cite>dbm.FluidParticle</cite> and <cite>dbm.InsolubleParticle</cite> report the properties and
behavior of the particle during the simulation. An interface to the <cite>dbm</cite>
objects is provided by the Particle class objects defined in
<cite>dispersed_phases</cite>.</p>
<div class="section" id="notes">
<h3>Notes<a class="headerlink" href="#notes" title="Permalink to this headline">¶</a></h3>
<p>This model solves for the trajectory <cite>vec(x)</cite> by the simple transport
equation:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d</span> <span class="n">vec</span><span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="o">/</span> <span class="n">dt</span> <span class="o">=</span> <span class="n">vec</span><span class="p">(</span><span class="n">u</span><span class="p">)</span>
</pre></div>
</div>
<p>where <cite>vec(u)</cite> is the vector velocity of the particle, which may include the
rise velocity and an ambient current. The rise velocity depends on the
particle size, which changes with pressure (if compressible) and as a result
of mass transfer (when soluble). Hence, this equation is usually coupled to a
system of equations for the change in mass of each chemical component in the
particle <cite>m_i</cite>, given by:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d</span> <span class="p">(</span><span class="n">m_i</span><span class="p">)</span> <span class="o">/</span> <span class="n">dt</span> <span class="o">=</span> <span class="o">-</span> <span class="n">beta</span> <span class="o">*</span> <span class="n">A</span> <span class="o">*</span> <span class="p">(</span><span class="n">Cs</span> <span class="o">-</span> <span class="n">C</span><span class="p">)</span>
</pre></div>
</div>
<p>where <cite>Cs</cite> is the local solubility of component <cite>i</cite> and <cite>C</cite> is the local
concentration of component <cite>i</cite> in the surrounding water; <cite>beta</cite> is the mass
transfer coefficient and <cite>A</cite> is the surface area.  Methods to compute
<cite>beta</cite>, <cite>Cs</cite>, and <cite>A</cite> are provided in the <cite>dbm</cite> module.  Since source fluids
may have different temperature than the ambient, heat transfer is also
modeled:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d</span> <span class="n">H</span> <span class="o">/</span> <span class="n">dt</span> <span class="o">=</span> <span class="o">-</span> <span class="n">rho_p</span> <span class="o">*</span> <span class="n">cp</span> <span class="o">*</span> <span class="n">A</span> <span class="o">*</span> <span class="n">beta_T</span> <span class="o">*</span> <span class="p">(</span><span class="n">T</span> <span class="o">-</span> <span class="n">Ta</span><span class="p">)</span>
</pre></div>
</div>
<p>where <cite>H</cite> is the heat content, given by <cite>m_p * cp * T</cite>; <cite>beta_T</cite> is the heat
transfer coefficient and <cite>m_p</cite> is the total mass of the particle.  Since some
mass is lost due to dissolution, the particle temperature must be adjusted
by:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d</span> <span class="n">H</span> <span class="o">/</span> <span class="n">dt</span> <span class="o">=</span> <span class="n">cp</span> <span class="o">*</span> <span class="n">d</span> <span class="p">(</span><span class="n">m_p</span><span class="p">)</span> <span class="o">/</span> <span class="n">dt</span> <span class="o">*</span> <span class="n">T</span>        <span class="c1"># Note d (m_p) / dt &lt; 0</span>
</pre></div>
</div>
<p>and for the heat of solution, using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">d</span> <span class="n">H</span> <span class="o">/</span> <span class="n">dt</span> <span class="o">=</span> <span class="nb">sum</span> <span class="p">(</span><span class="n">d</span> <span class="p">(</span><span class="n">m_i</span><span class="p">)</span> <span class="o">/</span><span class="n">dt</span> <span class="o">*</span> <span class="n">dH_solR_i</span> <span class="o">*</span> <span class="n">Ru</span> <span class="o">/</span> <span class="n">M_i</span><span class="p">)</span>
</pre></div>
</div>
<p>where <cite>dH_solR</cite> is the enthalpy of solution divided by the universal gas
constant (<cite>Ru</cite>) and <cite>M_i</cite> is the molecular weight of constituent <cite>i</cite>.</p>
<p>When the particle becomes very small, the heat transfer and dissolution
become unstable, leading to rapid oscillations in the predicted particle
temperature.  To avoid this problem, this module accounts for heat transfer
until the particle temperature reaches equilibrium with the seawater (which
happens very quickly).  Thereafter, the particle is assumed to be equal to
the temperature of the ambient water.</p>
<p>The equations for heat and mass transfer and for slip velocity are
discontinuous at the boundaries between particle shapes (e.g., ellipsoid and
spherical cap, etc.), and this can sometimes lead to the solution getting
stuck at the shape transition. The convergence criteria for the ODE solver are
set at an optimal compromise for accuracy and for allowing a diverse range of
particles to be simulated. Nonetheless, there are situations where these
discontinuities may still break the solution.</p>
<p>Finally, if the diameter of a fluid particle is observed to rapidly increase,
this is usually associated with a phase change from liquid to gas.  The
diagnostic plots help to identify these effects by plotting the state space
together with several descriptive variables, including diameter, density,
and shape.  However, there is no mechanism in this module to allow a droplet
to break up into multiple bubbles.</p>
</div>
</div>
<div class="section" id="class-objects-and-methods">
<h2>Class Objects and Methods<a class="headerlink" href="#class-objects-and-methods" title="Permalink to this headline">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">Model</span></code> object is the main interface to the <code class="docutils literal notranslate"><span class="pre">single_bubble_model</span></code>.  Its definition and methods are as follows:</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/sbm/single_bubble_model.Model.html#single_bubble_model.Model" title="single_bubble_model.Model"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Model</span></code></a>([profile, simfile])</p></td>
<td><p>Master class object for controlling and post-processing the simulation</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/sbm/single_bubble_model.Model.simulate.html#single_bubble_model.Model.simulate" title="single_bubble_model.Model.simulate"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Model.simulate</span></code></a>(self, particle, X0, de, yk[, …])</p></td>
<td><p>Simulate the trajectory of a particle from given initial conditions</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/sbm/single_bubble_model.Model.save_sim.html#single_bubble_model.Model.save_sim" title="single_bubble_model.Model.save_sim"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Model.save_sim</span></code></a>(self, fname, profile_path, …)</p></td>
<td><p>Save the current simulation results</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/sbm/single_bubble_model.Model.save_txt.html#single_bubble_model.Model.save_txt" title="single_bubble_model.Model.save_txt"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Model.save_txt</span></code></a>(self, base_name, …)</p></td>
<td><p>Save the state space in ascii text format for exporting</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/sbm/single_bubble_model.Model.load_sim.html#single_bubble_model.Model.load_sim" title="single_bubble_model.Model.load_sim"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Model.load_sim</span></code></a>(self, fname)</p></td>
<td><p>Load in a saved simulation result file for post-processing</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/sbm/single_bubble_model.Model.post_process.html#single_bubble_model.Model.post_process" title="single_bubble_model.Model.post_process"><code class="xref py py-obj docutils literal notranslate"><span class="pre">Model.post_process</span></code></a>(self[, fig])</p></td>
<td><p>Plot the simulation state space and key interrogation parameters</p></td>
</tr>
</tbody>
</table>
<p>All of the model parameters are contained in the <code class="docutils literal notranslate"><span class="pre">ModelParams</span></code> object.  This object is described in the following:</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/sbm/single_bubble_model.ModelParams.html#single_bubble_model.ModelParams" title="single_bubble_model.ModelParams"><code class="xref py py-obj docutils literal notranslate"><span class="pre">ModelParams</span></code></a>(profile)</p></td>
<td><p>Fixed model parameters for the single bubble model</p></td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="module-functions">
<h2>Module Functions<a class="headerlink" href="#module-functions" title="Permalink to this headline">¶</a></h2>
<p>The single bubble model objects defined above use several utilities to
perform their numerical tasks.  These are generally not intended to be called
directly by the user and are summarized below:</p>
<table class="longtable docutils align-default">
<colgroup>
<col style="width: 10%" />
<col style="width: 90%" />
</colgroup>
<tbody>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/sbm/single_bubble_model.calculate_path.html#single_bubble_model.calculate_path" title="single_bubble_model.calculate_path"><code class="xref py py-obj docutils literal notranslate"><span class="pre">calculate_path</span></code></a>(profile, particle, p, y0, delta_t)</p></td>
<td><p>Calculate the trajectory of a particle</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/sbm/single_bubble_model.derivs.html#single_bubble_model.derivs" title="single_bubble_model.derivs"><code class="xref py py-obj docutils literal notranslate"><span class="pre">derivs</span></code></a>(t, y, profile, particle, p)</p></td>
<td><p>Compute the RHS of the ODE for the trajectory of a single particle</p></td>
</tr>
<tr class="row-odd"><td><p><a class="reference internal" href="../autodoc/sbm/single_bubble_model.sbm_ic.html#single_bubble_model.sbm_ic" title="single_bubble_model.sbm_ic"><code class="xref py py-obj docutils literal notranslate"><span class="pre">sbm_ic</span></code></a>(profile, particle, X0, de, yk, T0, K, …)</p></td>
<td><p>Set the initial conditions for a single bubble model simulation</p></td>
</tr>
<tr class="row-even"><td><p><a class="reference internal" href="../autodoc/sbm/single_bubble_model.plot_state_space.html#single_bubble_model.plot_state_space" title="single_bubble_model.plot_state_space"><code class="xref py py-obj docutils literal notranslate"><span class="pre">plot_state_space</span></code></a>(profile, particle, p, t, y, fig)</p></td>
<td><p>Create the basic plots to interrogate the solution for the particle path</p></td>
</tr>
</tbody>
</table>
</div>
</div>


          </div>
          
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../index.html">Texas A&M Oil spill / Outfall Calculator</a></h1>








<h3>Navigation</h3>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="../user_manual.html">TAMOC User Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../unit_tests.html">Unit Tests</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../bugs.html">Reporting Bugs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../readme.html">Read Me File</a></li>
<li class="toctree-l1"><a class="reference internal" href="../release.html">Release Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="../license.html">License</a></li>
</ul>

<div class="relations">
<h3>Related Topics</h3>
<ul>
  <li><a href="../index.html">Documentation overview</a><ul>
  <li><a href="../user_manual.html">TAMOC User Manual</a><ul>
      <li>Previous: <a href="../autodoc/params/params.Scales.u_inf_crit.html" title="previous chapter">params.Scales.u_inf_crit</a></li>
      <li>Next: <a href="../autodoc/sbm/single_bubble_model.Model.html" title="next chapter">single_bubble_model.Model</a></li>
  </ul></li>
  </ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" />
      <input type="submit" value="Go" />
    </form>
    </div>
</div>
<script>$('#searchbox').show(0);</script>








        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="footer">
      &copy;2020, Scott A. Socolofsky.
      
      |
      Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>
      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
      
      |
      <a href="../_sources/modules/sbm.rst.txt"
          rel="nofollow">Page source</a>
    </div>

    

    
  </body>
</html>